Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Associating Movies With Controllers

Once your application has established a connection to a movie controller component, you may associate one movie with a movie controller. By default, the new controller has editing and keystroke processing turned off.

You create a new movie controller and assign it to a movie by calling the NewMovieController function. This is the easiest way to use a movie controller component.

If you want to exert more control over the assignment of movies to controllers, you can use other movie controller functions. If you want to assign a movie to an existing controller, you can use the MCNewAttachedController function. Use the MCSetMovie function to assign a movie to or remove a movie from a controller. You can use the MCGetMovie function to retrieve a reference to the movie that is assigned to a controller.

When you are done with a controller, use the DisposeMovieController function to dispose of the controller.

NewMovieController

The NewMovieController function locates a movie controller component for you and assigns a movie to that controller. This function always creates a controller that is attached to a movie.

This function is actually implemented by the Movie Toolbox, not by movie controller components. If you are creating your own movie controller component, you do not need to support this function.

pascal ComponentInstance NewMovieController (Movie theMovie,
                                         const Rect *movieRect,
                                         long someFlags);
theMovie
Identifies the movie to be associated with the movie controller.
movieRect
Points to the display rectangle that is to contain the movie and its controller.
someFlags
Contains flags that control the operation. If you set these flags to 0, the movie controller component centers the movie in the rectangle specified by the movieRect parameter and scales the movie to fit in that rectangle. The control portion of the controller is also placed within that rectangle. You may control how the movie and the control are drawn by setting one or more of the following flags to 1:
mcTopLeftMovie
If this flag is set to 1, the movie controller component places the movie into the upper-left corner of the display rectangle specified by the movieRect parameter. The component scales the movie to fit into the rectangle. Note that the control portion of the controller may fall outside of the rectangle, depending upon the results of the scaling operation.
If you set this flag and the mcScaleMovieToFit flag to 1, the movie controller component resizes the movie to fit into the specified rectangle and places the control portion of the controller outside of the rectangle.
mcScaleMovieToFit
If this flag is set to 1, the movie controller component resizes the movie to fit into the display rectangle specified by the movieRect parameter after it places the control portion of the controller into the rectangle.
If you set this flag and the mcTopLeftMovie flag to 1, the movie controller component resizes the movie to fit into the specified rectangle and places the control portion of the controller outside of the rectangle.
mcWithBadge
Controls whether the movie controller uses a badge (see "Badges," which begins on Badges , for more information about movie badges). If you set this flag to 1, the movie controller component displays the movie with a badge whenever the controller portion is not displayed. If you set this flag to 0, the movie controller component does not use a badge.
mcNotVisible
Controls whether the controller portion is visible. If you set this flag to 0, the movie controller component displays the controller along with the movie. If you set this flag to 1, the component does not display the controller. If you have set the mcWithBadge flag to 1, specifying that the component uses a badge, the component displays a badge whenever the controller is not visible.
mcWithFrame
Specifies whether the component displays a frame around the movie as part of the controller. If you set this flag to 1, the component displays a frame around the movie, including the movie's name. If you set this flag to 0, the component does not display a frame as part of the controller.

DESCRIPTION

The NewMovieController function returns a movie controller identifier value. This value identifies a connection to a movie controller component, and it is a component instance.

MCNewAttachedController

The MCNewAttachedController function associates a specified movie with a movie controller.

pascal ComponentResult MCNewAttachedController (MovieController
                                          mc, Movie theMovie,
                                          WindowPtr w,
                                          Point where);
mc
Specifies the movie controller for the operation. You obtain this identifier from the Component Manager's OpenComponent or OpenDefaultComponent function.
theMovie
Identifies the movie to be associated with the movie controller.
w
Identifies the window in which the movie is to be displayed. The movie controller component sets the movie's graphics world to match this window. If you set the w parameter to nil , the component uses the current window.
where
Specifies the upper-left corner of the movie within the window specified by the w parameter. The movie controller component uses the movie's boundary rectangle to determine the size of the movie (the Movie Toolbox's GetMovieBox function returns this rectangle).

DESCRIPTION

The MCNewAttachedController function forces the controller to be attached to the movie and sets the controller to be visible.

MCSetMovie

The MCSetMovie function associates a movie with a specified movie controller.

pascal ComponentResult MCSetMovie (MovieController mc,
                                         Movie theMovie,
                                         WindowPtr movieWindow,
                                         Point where);
mc
Specifies the movie controller for the operation. You obtain this identifier from the Component Manager's OpenComponent or OpenDefaultComponent function, or from the NewMovieController function (described on NewMovieController ).
theMovie
Identifies the movie to be associated with the movie controller. Set this value to nil to remove the movie from the controller.
movieWindow
Identifies the window in which the movie is to be displayed. The movie controller component sets the movie's graphics world to match this window. If you set the w parameter to nil , the component uses the current window.
where
Specifies the upper-left corner of the movie within the window specified by the movieWindow parameter. The movie controller component uses the movie's boundary rectangle to determine the size of the movie (the Movie Toolbox's GetMovieBox function returns this rectangle).

DESCRIPTION

You can also use the MCSetMovie function to remove a movie from its controller.

SEE ALSO

If you want to scale the movie, call the Movie Toolbox's SetMovieBox function (described in Inside Macintosh: QuickTime ) before calling MCSetMovie .

MCGetMovie

The MCGetMovie function allows your application to retrieve the movie reference for a movie that is associated with a movie controller. The movie controller component returns the movie's identifier value.

pascal Movie MCGetMovie (MovieController mc);
mc
Specifies the movie controller for the operation. You obtain this identifier from the Component Manager's OpenComponent or OpenDefaultComponent function, or from the NewMovieController function (described on NewMovieController ).

DESCRIPTION

The MCGetMovie function returns the movie identifier for the movie that is assigned to the specified controller. If there is no movie assigned to the controller, the returned movie identifier is set to nil .

DisposeMovieController

The DisposeMovieController function disposes of a movie controller. Your application is responsible for disposing of the movie that is associated with the movie controller. Do not dispose of the movie before disposing of the controller.

pascal void DisposeMovieController (ComponentInstance mc);
mc
Specifies the movie controller for the operation. You obtain this identifier from the Component Manager's OpenComponent or OpenDefaultComponent function, or from the NewMovieController function (described on NewMovieController ).

DESCRIPTION

The DisposeMovieController function is implemented by the Movie Toolbox, not by movie controller components. If you are creating your own movie controller component, you do not have to support this function.

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next